--  ---------------------------------------------------------------------------
--  @File: symbol.adb
--
--  @Project: LiberAda
--  @Version: 1.0
--  @Created: 2009-10-08
--  @Author:  Ivan Bogicevic
--
--  @Description:
--    Several tokens build up a symbol (e.g. the tokens "Ada", ".", "Text_IO"
--    form the symbol "Ada.Text_IO"). Here, the position of the symbol in the
--    source code and the kind of the symbol (e.g. GLOBAL_VARIABLE_T) are
--    stored. In the case that the symbol is a function or a procedure, the
--    types of all its parameters are also stored here.
--
--  @Modifications:
--
--  ---------------------------------------------------------------------------
with Ada.Strings.Unbounded;
with Ada.Containers.Vectors;

package Symbol is

   package ASU renames Ada.Strings.Unbounded;

   package String_Vector is new
      Ada.Containers.Vectors (Index_Type => Natural,
                              Element_Type => ASU.Unbounded_String,
                              "=" => ASU."=");

   type Symbol_Kind_Type is (PACKAGE_T, TYPE_T, CONSTANT_T, EXCEPTION_T,
      GLOBAL_VARIABLE_T, FUNCTION_AND_PROCEDURE_T, UNKNOWN_T, EMPTY_T);

   type Symbol_Type is tagged private;

   --  ------------------------------------------------------------------------
   --  @Procedure: Set_Filepath
   --  @Description: Simple setter-function for the filepath
   --  @Parameter:
   --    +Filepath: The path including filename to the ada source file
   procedure Set_Filepath
     (This     : in out Symbol_Type;
      Filepath : in     ASU.Unbounded_String);

   --  ------------------------------------------------------------------------
   --  @Procedure: Set_Packagename
   --  @Description: Simple setter-function for the packagename
   --  @Parameter:
   --    +Packagename: The name of the package wherein the symbol is
   procedure Set_Packagename
     (This        : in out Symbol_Type;
      Packagename : in     ASU.Unbounded_String);

   --  ------------------------------------------------------------------------
   --  @Procedure: Set_Name
   --  @Description: Simple setter-function for the name of the symbol
   --  @Parameter:
   --    +Name: The name as stringvalue of the symbol
   procedure Set_Name
     (This : in out Symbol_Type;
      Name : in     ASU.Unbounded_String);

   --  ------------------------------------------------------------------------
   --  @Procedure: Add_Parametertype
   --  @Description:
   --    Used only for symbols, which are procedures and functions and have
   --    parameters. The type of such a parameter can be added here.
   --  @Parameter:
   --    Parametertype: The type of the procedures' or functions' parameter
   procedure Add_Parametertype
     (This          : in out Symbol_Type;
      Parametertype : in     ASU.Unbounded_String);

   --  ------------------------------------------------------------------------
   --  @Procedure: Extend_Last_Parametertype
   --  @Description:
   --    Used only for symbols, which are procedures and functions and have
   --    parameters. The last type of such a parameter can be extended here.
   --  @Parameter:
   --    Parametertype: The string by which the procedures' or functions'
   --    last parameter shall be extended
   procedure Extend_Last_Parametertype
     (This      : in out Symbol_Type;
      Extension : in     ASU.Unbounded_String);

   --  ------------------------------------------------------------------------
   --  @Procedure: Set_Kind
   --  @Description: Simple setter-function for the kind of the symbol
   --  @Parameter:
   --    +Kind: The kind of the symbol (e.g. GLOBAL_VARIABLE_T)
   procedure Set_Kind
     (This : in out Symbol_Type;
      Kind : in     Symbol_Kind_Type);

   --  ------------------------------------------------------------------------
   --  @Procedure: Clear
   --  @Description: Resets all private data of the symbol to empty values.
   procedure Clear (This : in out Symbol_Type);

   --  ------------------------------------------------------------------------
   --  @Function: Get_Filenpath
   --  @Description: Simple getter-function for the filepath
   --  @Return: The path including filename to the ada source file
   function Get_Filepath (This : in Symbol_Type) return ASU.Unbounded_String;

   --  ------------------------------------------------------------------------
   --  @Function: Get_Packagename
   --  @Description: Simple getter-function for the packagename
   --  @Return: The name of the package wherein the symbol is
   function Get_Packagename (This : in Symbol_Type)
      return ASU.Unbounded_String;

   --  ------------------------------------------------------------------------
   --  @Function: Get_Name
   --  @Description: Simple getter-function for the name of the symbol
   --  @Return: The name as stringvalue of the symbol
   function Get_Name (This : in Symbol_Type) return ASU.Unbounded_String;

   --  ------------------------------------------------------------------------
   --  @Function: Get_Parametertype
   --  @Description:
   --    Only interesting for symbols, which are procedures and functions and
   --    have parameters. The types of all such parameters are read out here.
   --  @Return:
   --    The types of all the functions' or procedures' parameters. Empty, if
   --    the symbol is neither a function nor a procedure.
   function Get_Parametertypes (This : in Symbol_Type)
      return String_Vector.Vector;

   --  ------------------------------------------------------------------------
   --  @Function: Get_Kind
   --  @Description: Simple getter-functio for the kind of the symbol
   --  @Return: The kind of the symbol (e.g. GLOBAL_VARIABLE_T)
   function Get_Kind (This : in Symbol_Type) return Symbol_Kind_Type;

   --  ------------------------------------------------------------------------
   --  @Function: Get_ID
   --  @Description:
   --    By concatenating the string values of the private data of the symbol,
   --    a unique identified of it is generated.
   --  @Return: Unique identifier of the symbol
   function Get_ID (This : in Symbol_Type) return ASU.Unbounded_String;

   --  ------------------------------------------------------------------------
   --  @Function: Get_Link
   --  @Description:
   --    To find a specific symbol in all the html documents, its anchor-id is
   --    the value returned by this function. Links to the symbol have to
   --    include this to its href value.
   --  @Return: The link to the symbol as used in the html file
   function Get_Link (This : in Symbol_Type) return ASU.Unbounded_String;

   --  ------------------------------------------------------------------------
   --  @Function: "="
   --  @Description: Checks, if two symbols are equal
   --  @Parameter:
   --    +Left: The first symbol to check the equality with the second one
   --    +Right: The second symbol to check the equality with the first one
   --  @Return: True, if the IDs of the first and second symbols are equal
   function "=" (Left, Right : Symbol_Type) return Boolean;
   pragma Inline ("=");

private

   type Symbol_Type is tagged record
      Filepath       : ASU.Unbounded_String;
      Packagename    : ASU.Unbounded_String;
      Name           : ASU.Unbounded_String;
      Parametertypes : String_Vector.Vector;
      Kind           : Symbol_Kind_Type;
   end record;

end Symbol;
